Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

63장. 팀에 도입하기 — .claude/ 공유와 CI 자동 Review

지금까지는 개인의 이야기였다.

내 하네스, 내 Skill, 내 판단.

팀이 함께 쓰기 시작하면 성격이 바뀐다.

혼자와 여럿의 차이

혼자팀
내가 규칙을 안다규칙이 문서여야 한다
내 판단으로 예외예외에 합의가 필요
실수해도 내가 수습남의 코드에 영향
내 취향대로표준이 필요

🔥 여기서 좋은 소식이 하나 있다.

우리는 이미 팀용 하네스를 만들어왔다.

CLAUDE.md, settings.json, Skill, 아키텍처 테스트.
전부 파일이고 전부 커밋할 수 있다.

무엇을 커밋하는가

경계를 명확히 해둔다.

order-service/
  CLAUDE.md                    ✅ 커밋
  HARNESS.md                   ✅ 커밋
  .mcp.json                    ✅ 커밋 (토큰은 환경변수 참조)
  docs/                        ✅ 커밋
  .claude/
    settings.json              ✅ 커밋
    settings.local.json        ❌ .gitignore
    skills/                    ✅ 커밋
    agents/                    ✅ 커밋
    hooks/                     ✅ 커밋
  tasks/                       🟡 팀이 정한다
항목판단
팀 규칙·안전선커밋
개인 실험적 허용커밋 안 함
진행 중 작업 문서팀이 정한다

⚠️ tasks/ 가 애매하다.

커밋하면 인계가 팀 전체로 확장되고,
안 하면 개인 작업 공간이 된다.

19장에서 말한 대로 정하는 것이 중요하다.
정하지 않으면 반쯤 커밋된 상태가 된다.

도입 순서

한 번에 전사로 가지 않는다.

flowchart LR
    A[한 사람<br/>2~4주] --> B[한 팀<br/>4~8주]
    B --> C[여러 팀]

1단계 — 한 사람

한 명이 실제 작업에 쓰면서 하네스를 만든다.

산출물은 8장에서 만든 것들이다.

CLAUDE.md
.claude/settings.json
빠른 테스트 명령

⚠️ 이 단계를 건너뛰면 안 된다.

써보지 않은 사람이 만든 규칙은
대개 실제 문제를 못 짚는다.

2단계 — 한 팀

팀에 열고 반응을 본다.

이때 필요한 것은 도구가 아니라 합의다.

팀이 합의해야 하는 다섯 가지

1. 무엇을 Agent에게 맡기고 무엇을 안 맡기는가
2. Diff 검토 없이 커밋해도 되는 경우가 있는가
3. Agent 사용 여부를 기록하는가 (59장)
4. 개인 설정으로 팀 deny 를 뚫어도 되는가
5. 규칙 예외는 누가 승인하는가

⚠️ 네 번째가 실제로 문제가 된다.

"급해서 제 로컬 설정에서 풀고 했어요"

기술적으로 가능하다.
그래서 합의가 필요하다.

🔥 다섯 번째의 답은 대개 “리뷰어” 다.

42장에서 아키텍처 테스트 예외를 추가할 때,
그것도 PR에 드러나므로 리뷰 대상이 된다.

CLAUDE.md는 온보딩 문서다

부수 효과지만 크게 온다.

CLAUDE.md 를 읽으면 알 수 있는 것

- 빌드·테스트·로컬 실행 방법
- 디렉터리 구조와 각 영역의 역할
- 계층 규칙과 호출 방향
- 코딩 컨벤션 (현재 표준이 무엇인지)
- 도메인 용어
- 절대 하지 말 것

신규 입사자에게 필요한 목록과 같다.

4장에서 말한 그대로다.
Agent에게 명시해야 했던 것이 사람에게도 유용하다.

"온보딩 문서를 따로 만들지 않고
CLAUDE.md 를 읽게 한다"

이렇게 하면 문서가 하나로 유지된다.
두 벌이면 한쪽이 반드시 낡는다.

CI에서 Agent를 쓴다

여기서 새로운 이야기가 하나 나온다.

Claude Code는 대화 없이도 실행할 수 있다.

claude -p "이 PR의 Diff를 아키텍처 규칙 관점에서 검토하고
문제가 있으면 파일:줄과 함께 지적해줘" --output-format json

이것을 CI에 붙인다.

- name: 아키텍처 리뷰
  run: |
    claude -p "$(cat .github/review-prompt.md)" \
      --output-format json > review.json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

⚠️ 무엇을 시킬지가 중요하다.

CI에 맞는 것맞지 않는 것
규칙 위반 지적코드 자동 수정
누락 검사 (권한·테스트)설계 판단
PR 설명 초안 생성머지 결정
마이그레이션 체크리스트배포

🔥 기준은 59장과 같다.
읽고 지적까지, 실행은 사람이.

그리고 결정론적으로 검사할 수 있는 것은
Agent가 아니라 그냥 테스트로 만든다.

42장의 아키텍처 테스트가 있으면
CI에서 Agent가 그것을 다시 볼 필요가 없다.

Agent를 CI에 쓰는 이유는
테스트로 표현할 수 없는 것을 보기 위해서다.

리뷰 문화가 바뀐다

팀에 퍼지면 리뷰의 성격이 달라진다.

전    "이 코드 왜 이렇게 썼어요?"
후    "이 방향으로 가기로 한 근거가 뭔가요?"

Diff 자체는 Agent가 만들었고
사람이 결정한 것은 방향이다.

그래서 리뷰가 두 층으로 나뉜다.

층무엇을 본다
방향계획이 맞았는가 (21장의 계획서)
구현Diff가 계획대로인가

21장에서 계획을 문서로 남기라고 한 이유가
팀 리뷰에서 회수된다.

반발과 그 이유

⚠️ 도입하면 반대 의견이 나온다.

미리 알아두면 대응이 쉽다.

우려사실
코드 품질이 떨어진다하네스가 없으면 맞다
실력이 늘지 않는다검토를 안 하면 맞다
코드가 외부로 나간다정책 확인이 필요하다 (59장)
결국 내가 다 고친다작업 정의가 부족하면 맞다
리뷰 부담이 늘어난다커밋을 작게 안 나누면 맞다

🔥 다섯 개 모두 조건부로 맞다.

그래서 반박하는 것보다
그 조건을 없애는 편이 낫다.

"품질이 떨어진다"       → 아키텍처 테스트와 Review Agent를 보여준다
"리뷰 부담이 늘어난다"   → 커밋 단위 규칙을 먼저 합의한다

⚠️ 그리고 강제하지 않는다.

쓰지 않는 사람이 있어도 하네스는 이득이다.
테스트와 규칙은 사람에게도 적용된다.

12부를 마치며

네 장에서 한 일이다.

60장  진단 기준을 세웠다
61장  우리 하네스를 그렸다
62장  고치는 절차를 만들었다
63장  팀으로 확장했다

이제 남은 것은 실전이다.

13부에서 지금까지 만든 것을 전부 써서
세 가지 작업을 처음부터 끝까지 한다.

이 장의 핵심

  • 우리가 만들어온 하네스는 이미 전부 파일이고 커밋할 수 있다
  • 팀 규칙은 커밋하고 개인 실험은 커밋하지 않는다
  • tasks/ 커밋 여부는 정하는 것이 중요하다 — 안 정하면 반쯤 커밋된다
  • 한 사람이 먼저 써보지 않으면 실제 문제를 못 짚는 규칙이 나온다
  • 팀 합의가 필요한 것은 다섯 가지다 — 특히 개인 설정으로 팀 규칙을 뚫는 문제
  • CLAUDE.md 가 온보딩 문서 역할을 한다 — 두 벌이면 한쪽이 낡는다
  • CI에서는 읽고 지적까지만 시킨다
  • 결정론적으로 검사할 수 있는 것은 Agent가 아니라 테스트로 만든다
  • Agent를 CI에 쓰는 이유는 테스트로 표현할 수 없는 것을 보기 위해서다
  • 리뷰가 방향과 구현 두 층으로 나뉜다
  • 반발은 대부분 조건부로 맞다 — 반박보다 그 조건을 없애는 편이 낫다